27.15 Additional Options for Displaying Buffers

The behavior of the standard display actions of display-buffer (see Choosing Window) can be modified by a variety of user options.

User Option: pop-up-windows

If the value of this variable is non-nil, display-buffer is allowed to split an existing window to make a new window for displaying in. This is the default.

This variable is provided mainly for backward compatibility. It is obeyed by display-buffer via a special mechanism in display-buffer-fallback-action, which only calls the action function display-buffer-pop-up-window (see Display Action Functions) when the value is nil. It is not consulted by display-buffer-pop-up-window itself, which the user may specify directly in display-buffer-alist etc.

User Option: split-window-preferred-function

This variable specifies a function for splitting a window, in order to make a new window for displaying a buffer. It is used by the display-buffer-pop-up-window action function to actually split the window (see Display Action Functions).

The default value is split-window-sensibly, which is documented below. The value must be a function that takes one argument, a window, and return either a new window (which will be used to display the desired buffer) or nil (which means the splitting failed).

Function: split-window-sensibly &optional window

This function tries to split window, and return the newly created window. If window cannot be split, it returns nil. If window is omitted or nil, it defaults to the selected window.

This function obeys the usual rules that determine when a window may be split (see Splitting Windows). It first tries to split by placing the new window below, subject to the restriction imposed by split-height-threshold (see below), in addition to any other restrictions. If that fails, it tries to split by placing the new window to the right, subject to split-width-threshold (see below). If that fails, and the window is the only window on its frame, this function again tries to split and place the new window below, disregarding split-height-threshold. If this fails as well, this function gives up and returns nil.

User Option: split-height-threshold

This variable, used by split-window-sensibly, specifies whether to split the window placing the new window below. If it is an integer, that means to split only if the original window has at least that many lines. If it is nil, that means not to split this way.

User Option: split-width-threshold

This variable, used by split-window-sensibly, specifies whether to split the window placing the new window to the right. If the value is an integer, that means to split only if the original window has at least that many columns. If the value is nil, that means not to split this way.

User Option: even-window-sizes

This variable, if non-nil, causes display-buffer to even window sizes whenever it reuses an existing window and that window is adjacent to the selected one.

If its value is width-only, sizes are evened only if the reused window is on the left or right of the selected one and the selected window is wider than the reused one. If its value is height-only sizes are evened only if the reused window is above or beneath the selected window and the selected window is higher than the reused one. Any other non-nil value means to even sizes in any of these cases provided the selected window is larger than the reused one in the sense of their combination.

User Option: pop-up-frames

If the value of this variable is non-nil, that means display-buffer may display buffers by making new frames. The default is nil.

A non-nil value also means that when display-buffer is looking for a window already displaying buffer-or-name, it can search any visible or iconified frame, not just the selected frame.

This variable is provided mainly for backward compatibility. It is obeyed by display-buffer via a special mechanism in display-buffer-fallback-action, which calls the action function display-buffer-pop-up-frame (see Display Action Functions) if the value is non-nil. (This is done before attempting to split a window.) This variable is not consulted by display-buffer-pop-up-frame itself, which the user may specify directly in display-buffer-alist etc.

User Option: pop-up-frame-function

This variable specifies a function for creating a new frame, in order to make a new window for displaying a buffer. It is used by the display-buffer-pop-up-frame action function (see Display Action Functions).

The value should be a function that takes no arguments and returns a frame, or nil if no frame could be created. The default value is a function that creates a frame using the parameters specified by pop-up-frame-alist (see below).

User Option: pop-up-frame-alist

This variable holds an alist of frame parameters (see Frame Parameters), which is used by the default function in pop-up-frame-function to make a new frame. The default is nil.

User Option: same-window-buffer-names

A list of buffer names for buffers that should be displayed in the selected window. If a buffer’s name is in this list, display-buffer handles the buffer by showing it in the selected window.

User Option: same-window-regexps

A list of regular expressions that specify buffers that should be displayed in the selected window. If the buffer’s name matches any of the regular expressions in this list, display-buffer handles the buffer by showing it in the selected window.

Function: same-window-p buffer-name

This function returns t if displaying a buffer named buffer-name with display-buffer would put it in the selected window.